home *** CD-ROM | disk | FTP | other *** search
/ The Programmer Disk / The Programmer Disk (Microforum).iso / xpro / pascal / pro17 / async12.doc < prev    next >
Text File  |  1989-07-20  |  12KB  |  257 lines
  1.                                     ASYNC12
  2.         Asyncronous Serial Communications Package for Turbo Pascal V5.0
  3.                              Version 1.2 - 06/14/89
  4.                  Copyright (C) 1989, Rising Edge Data Services
  5.  
  6. ASYNC12 is a full-featured Turbo Pascal UNIT that provides interrupt-driven
  7. serial communication PC-compatable computers utilizing standard serial port
  8. hardware (INS 8250's or equivalent).  Unlike similar offerings for Pascal
  9. programmers, ASYNC12 supports full input and output buffering for up to 4
  10. ports operating CONCURRENTLY, with optional full hardware and/or software
  11. handshaking.  In addition, key high-demand subroutines as well as the int-
  12. errupt driver are implimented in assembly language for maximum performance.
  13. Baud rates to 115200 are supported, as well as non-standard rates and all
  14. possible wordsize/parity/stopbit combinations allowed by the 8250 UART.
  15.  
  16. Features -- Version 1.2
  17. =======================
  18.  
  19. *  Supports up to 4 ports simultaneously.
  20. *  Completely interrupt driven I/O for greatest efficiency.
  21. *  Assembly language used for the interrupt driver and key high-performance
  22.    procedures and functions maximize throughput.
  23. *  Created as a Turbo Pascal UNIT for ease of use.
  24. *  Tight, well-commented, structured code for ease of modification/enhancement.
  25.    Includes both Pascal and Assembly source.
  26. *  Supports both hardware (RTS/CTS) and software (XON/XOFF) handshaking,
  27.    at the user's option.
  28. *  28 procedures and functions in all to minimize programmer design time.
  29.  
  30. ASYNC12 supports the serial ports mapped at the following addresses and hard-
  31. ware interrupt lines:
  32.  
  33. Port#  Address  Interrupt
  34. -----  -------  ---------
  35. COM1    03F8h       4
  36. COM2    02F8h       3
  37. COM3    03E8h       4
  38. COM4    02E8h       3
  39.  
  40. The port addresses may be reassigned by changing the contents of the global
  41. constant array C_PortAddr.  For example, to map COM3 at address 3D8h, you
  42. might code it like this (should be done before OpenCom is called) :
  43.  
  44. C_PortAddr[3] := $3D8;
  45.  
  46. To change interrupt priorities (i.e. which hardware interrupt line a port
  47. uses), change the appropriate element in the global constant array
  48. C_PortInt.  For example, if COM1 is wired to use INT5, make the following
  49. assignment (before calling OpenCom):
  50.  
  51. C_PortInt[1] := 5;
  52.  
  53. Finally, the number of ports supported can be changed, although recompilation
  54. of the unit is nessesary in this case.  Load the unit and change the constant
  55. C_MaxPort to the highest available port.  Then fill in the defaults for
  56. C_PortAddr and C_PortInt as appropriate and recompile the unit.
  57.  
  58. ASYNC12 will most likely NOT work with multiport boards (like the GTEK PCSS-4
  59. and -8 models) that use one standard COM port address to "multiplex" 2 or more
  60. ports.  ASYNC12 WILL support the "currently active port" on such boards, but
  61. does NOT support the port switching mechanisim nessesary for full utilization
  62. of these boards, although it may be possible to modify the code for this.
  63.  
  64. Available procedures and functions
  65. ==================================
  66.  
  67. User-accessable procedures and functions will be listed below along with a
  68. concise explaination of their function.  For more complete documentation and
  69. revision information, refer to the Pascal source code.
  70.  
  71. In all cases:  ComPort = Port # to use, range = 1 to C_MaxPort (usually 4).
  72.  
  73. Procedure ClearCom(ComPort:Byte; IO:Char);
  74.   - Clear input (IO='I'), output (IO='O') or both (IO='B') buffers
  75.  
  76. Procedure CloseCom(ComPort:Byte);
  77.   - Close a port previously opened for I/O
  78.  
  79. Procedure CloseAllComs;
  80.   - Close ALL active ports
  81.  
  82. Function ComBufferLeft(ComPort:Byte; IO:Char) : Word;
  83.   - Returns #bytes free in the input (IO='I') or output (IO='O') buffers
  84.  
  85. Function ComExist(ComPort:Byte) : Boolean;
  86.   - Performs a hardware-based test to determine if a port exists
  87.  
  88. Function ComReadCh(ComPort:Byte) : Char;
  89.   - Get one character from the selected input buffer
  90.  
  91. Function ComReadChW(ComPort:Byte) : Char;
  92.   - Get one character from the selected input buffer, wait for it if nessesary
  93.  
  94. Procedure ComReadln(ComPort:Byte; Var St:String; Size:Byte; Echo:Boolean);
  95.   - Get a string from the selected port.  Echoback & simple editing supported
  96.  
  97. Function ComTrueBaud(Baud:Longint) : Real;
  98.   - Compute actual baud rate that the hardware will transmit at
  99.  
  100. Procedure ComParams(ComPort:Byte; Baud:LongInt; WordSize:Byte; Parity:Char; StopBits:Byte);
  101.   - Set baud rate, word size, parity and stop bit options for selected port
  102.  
  103. Procedure ComWaitForClear(ComPort:Byte);
  104.   - Suspend execution until selected port's output buffer is clear
  105.  
  106. Procedure ComWrite(ComPort:Byte; St:String);
  107.   - Send a string out the selected port (place in output buffer)
  108.  
  109. Procedure ComWriteCh(ComPort:Byte; Ch:Char);
  110.   - Place a character in the output buffer of the selected port
  111.  
  112. Procedure ComWriteChW(ComPort:Byte; Ch:Char);
  113.   - Place character in output buffer, waiting for buffer space if nessesary.
  114.  
  115. Procedure ComWriteln(ComPort:Byte; St:String);
  116.   - Send string out selected port with appended CR/LF.
  117.  
  118. Procedure ComWriteWithDelay(ComPort:Byte; St:String; Dly:Word);
  119.   - Send string out selected port, delaying between character transmissions
  120.  
  121. Function CTSStat(ComPort:Byte) : Boolean;
  122.   - Returns status of RS232 "Clear To Send" (CTS) signal line (pin 5)
  123.  
  124. Function DCDStat(ComPort:Byte) : Boolean;
  125.   - Returns status of RS232 "Data Carrier Detect" (DCD) signal line (pin 8)
  126.  
  127. Function DSRStat(ComPort:Byte) : Boolean;
  128.   - Returns status of RS232 "Data Set Ready" (DSR) signal line (pin 6)
  129.  
  130. Function OpenCom(ComPort:Byte; InBufferSize,OutBufferSize:Word) : Boolean;
  131.   - Prepares communications system for I/O on selected port
  132.  
  133. Function RIStat(ComPort:Byte) : Boolean;
  134.   - Returns status of RS232 Ring Indicator (RI) signal line (pin 22)
  135.  
  136. Procedure SetCTSMode(ComPort:Byte; Mode:Boolean);
  137.   - Enables or disables built-in CTS hardware handshaking for transmission
  138.  
  139. Procedure SetDTR(ComPort:Byte; Assert:Boolean);
  140.   - Provides control for the RS232 "Data Terminal Ready" (DTR) line (pin 20)
  141.  
  142. Procedure SetOUT1(ComPort:Byte; Assert:Boolean);
  143.   - Controls logic level (ASSERT=TRUE for low level) of 8250 OUT1 signal line
  144.  
  145. Procedure SetOUT2(ComPort:Byte; Assert:Boolean);
  146.   - Controls logic level (ASSERT=TRUE for low level) of 8250 OUT2 signal line.
  147.     Used as a redundant mechanisim for controlling 8250 interrupts on PC's.
  148.  
  149. Procedure SetRTS(ComPort:Byte; Assert:Boolean);
  150.   - Provides control for the RS232 "Request To Send" (RTS) line (pin 4)
  151.     Note: Avoid using this procedure if automatic RTS handshaking enabled.
  152.  
  153. Procedure SetRTSMode(ComPort:Byte; Mode:Boolean; RTSOn,RTSOff:Word);
  154.   - Enables or disables RTS hardware handshake for reception
  155.     Also controls assert/unassert points when enabled.
  156.  
  157. Procedure SoftHandshake(ComPort:Byte; Mode:Boolean; Start,Stop:Char);
  158.   - Enables or disables XON/XOFF software handshake (transmission ONLY).
  159.     Also allows XON/XOFF characters to be redefined.
  160.  
  161. Variable(s)             Type            Function
  162. ----------------------  --------------  ----------------------------------
  163. C_InBufPtr,C_OutBufPtr  C_PointerArray  Input/output buffer pointers
  164. C_InHead,C_OutHead      C_WordArray     Input/output head pointers
  165. C_InTail,C_OutTail      C_WordArray     Input/output tail pointers
  166. C_InSize,C_OutSize      C_WordArray     Input/output buffer sizes
  167. C_RTSOn,C_RTSOff        C_WordArray     RTS assert/drop buffer points
  168. C_StartChar,C_StopChar  C_CharArray     Soft hndshake start/stop char
  169. C_Status,C_Ctrl         C_ByteArray     STATUS and CONTROL registers
  170. C_PortOpen              C_BooleanArray  Port open/close flags
  171. C_PortAddr              C_WordArray     Base address of 8250 UART for port
  172. C_PortInt               C_ByteArray     Hard INT line used by UART for port
  173.  
  174. Status byte definition (C_Status):
  175.   7   6   5   4   3   2   1   0
  176.   |   |   |   |   |   |   |   |____ Input buffer empty
  177.   |   |   |   |   |   |   |________ Input buffer full
  178.   |   |   |   |   |   |____________ Output buffer empty
  179.   |   |   |   |   |________________ Output buffer full
  180.   |   |   |   |____________________ Input buffer overflow
  181.   |   |   |________________________ Output buffer overflow
  182.   |   |____________________________ Hard handshake active (xmit stopped)
  183.   |________________________________ Soft handshake active (xmit stopped)
  184.  
  185. Control byte definition (C_Ctrl):
  186.   7   6   5   4   3   2   1   0
  187.   |   |   |   |   |   |   |   |____ Enable RTS handshake
  188.   |   |   |   |   |   |   |________ Enable CTS handshake
  189.   |   |   |   |   |   |____________ Enable software handshake (xmit only)
  190.   |   |   |   |   |________________
  191.   |   |   |   |____________________
  192.   |   |   |________________________
  193.   |   |____________________________
  194.   |________________________________ Pyrotronics XL3 mode (do not use!)
  195.  
  196. Files in archive:
  197. -----------------
  198. ASYNC12.PAS     - Pascal unit source code
  199. ASYNC12.ASM     - Assembly source for external routines and communications
  200.                   interrupt service routines.
  201. ASYNC12.DOC     - This file
  202. ASYNC.OBJ       - Assembled ASYNC.ASM
  203. ASYNC12.TPU     - Compiled ready-to-use Turbo Pascal V5.0 UNIT
  204.  
  205. Note to Assembly-language programmers:  The ASYNC.ASM source file was assembled
  206. using Borland's Turbo Assembler (V1.0).  Since the assembler's IDEAL mode
  207. was used throught, it will require some modifications to the source to get it
  208. to assemble properly with MASM.  The ASYNC12.PAS file expects to find the
  209. file "ASYNC.OBJ" in a directory locatable by the compiler (usually the same
  210. dir as the source) at compile-time.  The "{$L ASYNC.OBJ}" compiler directive
  211. controls this -- you may change the file path if it suits you.
  212.  
  213. ==============================================================================
  214.  
  215. DISCLAIMER and USAGE AGREEMENT:
  216.  
  217. Yes, this is the place where the standard batch of legalese goes.  When trans-
  218. lated into English it usually boils down to "Use of this program is your
  219. responsibility and not ours".  Effort has been made to provide software that
  220. is beleived to function as documented, but no guarantees can be made as to
  221. whether or not it will ever work out for you.  If this software malfunctions
  222. and, let's say your house or business burns down or blows itself up because
  223. of that malfunction, you're responsible for covering the loss -- not us.
  224. In short, if you use this software, and you experience loss and/or inconven-
  225. ience because of it, tough! (And if the world were populated exclusively by
  226. reasonable people, instead of those types that file lawsuits whenever someone
  227. looks at them the wrong way, time- and space-wasting statements like this
  228. would be unnessesary).
  229.  
  230. Permission is hereby granted to distribute this package (the "software" ) to
  231. friends, over information networks or through public-domain distribution houses
  232. provided this documentation accompanies it.  This software may NOT be
  233. distributed for profit or monetary gain (other than the single-disk asking
  234. price of a shareware distributor used to cover duplication and distribution
  235. costs, not to exceed $10 in any event).  Rising Edge Data Services reserves
  236. all copyrights in regard to the software and the accompanying documentation
  237. and may change the software without notice.
  238.  
  239. With that out of the way, your comments, suggestions, bug reports (and
  240. donations, $20 suggested) are welcome.  Any donations will be used to finance
  241. improvements to this and other forthcoming modules.
  242.  
  243. You may reach me in the following ways:
  244.  
  245. Via US Mail:                           Via Modem
  246. ------------------------               ---------------------------
  247. Mark L. Schultz                        Best Power Technology BBS
  248. Rising Edge Data Services              Necedah, WI  USA
  249. 201 Liberty St. Apt. #4                User name: Mark Schultz (or SYSOP)
  250. Mauston, WI  USA 53948                 Phone: (608) 565-7424
  251. Voice: (608) 847-4287
  252.  
  253. I can also be reached at the Exec-PC multiuser BBS based in Milwaukee, WI USA
  254. Phone: 414-964-5160.  Username: Best Power
  255.  
  256. ==============================================================================
  257.